Skip to content

Align public api#209

Merged
nikhilNava merged 4 commits intomainfrom
nikhilc/AlignPublicAPI
Mar 26, 2026
Merged

Align public api#209
nikhilNava merged 4 commits intomainfrom
nikhilc/AlignPublicAPI

Conversation

@nikhilNava
Copy link
Copy Markdown
Contributor

@nikhilNava nikhilNava commented Mar 25, 2026 •
edited
Loading

Task
Align public API across the 3 languages of observability SDK

Solution

{
    "name": "Chat gpt-4o-mini",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0xc6f8c689ee7f31d2",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x2c2187ce3dc20fa6",
    "start_time": "2026-03-25T20:01:45.581311Z",
    "end_time": "2026-03-25T20:01:50.863487Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.channel.name": "msteams",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "microsoft.a365.agent.blueprint.id": "4a380e3b-7092-4d73-bb9d-b6a54702684af",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "gen_ai.input.messages": "Calculate 29 modules 3\n\nTool result: Calculation result for 2 + 2: 42",
        "gen_ai.operation.name": "Chat",
        "gen_ai.request.model": "gpt-4o-mini",
        "gen_ai.provider.name": "Azure OpenAI",
        "gen_ai.output.messages": "\"To calculate 29 modulo 3, you divide 29 by 3 and find the remainder.\\n\\n29 divided by 3 is 9 with a remainder of 2. \\n\\nSo, 29 modulo 3 is **2**.\"",
        "gen_ai.usage.input_tokens": 48,
        "gen_ai.usage.output_tokens": 49,
        "gen_ai.response.finish_reasons": "[\"stop\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}
{
    "name": "output_messages 84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0x57c049a325f2f7ea",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x2c2187ce3dc20fa6",
    "start_time": "2026-03-25T20:01:50.866188Z",
    "end_time": "2026-03-25T20:01:50.868889Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.operation.name": "output_messages",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "nikhilcPermTest",
        "gen_ai.agent.description": "agenticUser",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "gen_ai.output.messages": "[\"To calculate 29 modulo 3, you divide 29 by 3 and find the remainder.\\n\\n29 divided by 3 is 9 with a remainder of 2. \\n\\nSo, 29 modulo 3 is **2**.\"]",
        "user.id": "a92962f3-9ed4-4bcd-9ae0-ad0002b6ca76",
        "user.name": "Alex Wilber",
        "microsoft.channel.name": "msteams"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}
{
    "name": "invoke_agent Azure OpenAI Agent",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0x2c2187ce3dc20fa6",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2026-03-25T20:01:43.897292Z",
    "end_time": "2026-03-25T20:01:50.874290Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.channel.name": "msteams",
        "user.id": "a92962f3-9ed4-4bcd-9ae0-ad0002b6ca76",
        "user.name": "Alex Wilber",
        "gen_ai.operation.name": "invoke_agent",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "microsoft.a365.agent.blueprint.id": "4a380e3b-7092-4d73-bb9d-b6a54702684af",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "microsoft.session.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "gen_ai.input.messages": "[\"Calculate 29 modules 3\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}

@nikhilNava nikhilNava requested review from a team as code owners March 25, 2026 18:53
Copilot AI review requested due to automatic review settings March 25, 2026 18:53
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 25, 2026 •
edited
Loading

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA d884db3.
Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

Copilot AI reviewed Mar 25, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Aligns the Python observability SDK public API with the other language SDKs by consolidating request/span configuration, renaming invocation configuration types, and removing execution-type / tenant-details concepts from the public surface.

Changes:

  • Introduces Request + SpanDetails as the primary way to pass conversation/session metadata and span configuration (parent context, timing, kind).
  • Replaces InvokeAgentDetails with InvokeAgentScopeDetails and updates all scope start(...) signatures accordingly.
  • Adds UserDetails + updates CallerDetails composition model; removes ExecutionType / GEN_AI_EXECUTION_TYPE_KEY usage across hosting + extensions + tests + docs.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
tests/usage_example.py Updates example usage to new Request/InvokeAgentScopeDetails API and removes execution type + tenant usage.
tests/observability/hosting/scope_helpers/test_scope_helper_utils.py Removes execution-type pair helper/test to match removed attribute.
tests/observability/hosting/scope_helpers/test_populate_invoke_agent_scope.py Updates scope construction + removes execution-type assertions.
tests/observability/hosting/middleware/test_output_logging_middleware.py Updates middleware expectations (tenant optional; parent passed via SpanDetails).
tests/observability/extensions/openai/integration/test_openai_trace_processor.py Aligns baggage builder API (user_*, agentic_user_*) and removes execution type expectation.
tests/observability/core/test_trace_context_propagation.py Migrates scope creation to Request + SpanDetails; removes tenant details usage.
tests/observability/core/test_record_attributes.py Removes tenant details from OpenTelemetryScope construction.
tests/observability/core/test_output_scope_bounded.py Updates AgentDetails fields to agentic_user_* and removes tenant mock.
tests/observability/core/test_output_scope.py Updates OutputScope.start(...) usage to new signature and parent via SpanDetails.
tests/observability/core/test_invoke_agent_scope.py Updates to InvokeAgentScopeDetails, Request, SpanDetails, UserDetails composition.
tests/observability/core/test_inference_scope.py Updates InferenceScope.start(...) signature and removes execution type / tenant usage.
tests/observability/core/test_execute_tool_scope.py Updates ExecuteToolScope.start(...) signature and parent/span kind via SpanDetails.
tests/observability/core/test_custom_start_end_time.py Moves custom timing into SpanDetails and updates ExecuteToolScope.start(...) signature.
tests/observability/core/test_baggage_builder.py Renames baggage builder methods to user_* and agentic_user_*.
libraries/microsoft-agents-a365-observability-hosting/.../scope_helpers/utils.py Removes execution type derivation helper and related constant imports.
libraries/microsoft-agents-a365-observability-hosting/.../populate_invoke_agent_scope.py Stops recording execution type attribute during scope population.
libraries/microsoft-agents-a365-observability-hosting/.../populate_baggage.py Stops populating execution type into baggage.
libraries/microsoft-agents-a365-observability-hosting/.../middleware/output_logging_middleware.py Switches to Request + SpanDetails + UserDetails, removes tenant/execution-type tagging.
libraries/microsoft-agents-a365-observability-extensions-semantickernel/.../span_processor.py Removes execution-type tagging for invoke-agent spans.
libraries/microsoft-agents-a365-observability-extensions-openai/.../trace_processor.py Removes execution-type attribute tagging for agent spans.
libraries/microsoft-agents-a365-observability-extensions-langchain/.../utils.py Removes set_execution_type() helper and execution-type constants usage.
libraries/microsoft-agents-a365-observability-extensions-langchain/.../tracer.py Stops injecting execution-type attribute into spans.
libraries/microsoft-agents-a365-observability-core/.../trace_processor/util.py Removes gen_ai.execution.type from exported attribute list.
libraries/microsoft-agents-a365-observability-core/.../spans_scopes/output_scope.py Updates OutputScope API to accept Request/SpanDetails/UserDetails and records conversation + user attributes.
libraries/microsoft-agents-a365-observability-core/.../span_details.py Adds SpanDetails dataclass for parent context, timing, and span kind.
libraries/microsoft-agents-a365-observability-core/.../request.py Makes request content optional and adds conversation_id.
libraries/microsoft-agents-a365-observability-core/.../opentelemetry_scope.py Removes tenant details support; aligns agentic user fields; factors cancel error type constant.
libraries/microsoft-agents-a365-observability-core/.../models/user_details.py Introduces UserDetails model for human caller metadata.
libraries/microsoft-agents-a365-observability-core/.../models/caller_details.py Redefines CallerDetails as composite of UserDetails and optional caller agent details.
libraries/microsoft-agents-a365-observability-core/.../middleware/baggage_builder.py Renames fluent methods to agentic_user_* and user_*.
libraries/microsoft-agents-a365-observability-core/.../invoke_agent_scope.py Aligns invocation scope signature + attribute recording with new models and SpanDetails.
libraries/microsoft-agents-a365-observability-core/.../invoke_agent_details.py Renames to InvokeAgentScopeDetails and narrows to scope-level config.
libraries/microsoft-agents-a365-observability-core/.../inference_scope.py Aligns inference scope signature + user/conversation attribute recording with new models.
libraries/microsoft-agents-a365-observability-core/.../execute_tool_scope.py Aligns tool scope signature + user/conversation attribute recording with new models.
libraries/microsoft-agents-a365-observability-core/.../constants.py Removes execution-type constant and adds cancellation error type constant.
libraries/microsoft-agents-a365-observability-core/.../agent_details.py Renames agent identity fields to agentic_user_* and removes conversation_id.
libraries/microsoft-agents-a365-observability-core/.../init.py Updates public exports to new classes and removes deprecated ones.
libraries/microsoft-agents-a365-observability-core/docs/design.md Updates design doc for new API surface and data models.
docs/design.md Updates repo-level design doc to new class names and usage patterns.
Comments suppressed due to low confidence (1)

libraries/microsoft-agents-a365-observability-core/docs/design.md:1

  • The fluent API names shown here don’t match the updated BaggageBuilder implementation (agentic_user_id(...) and agentic_user_email(...), not agent_auid(...) / agent_email(...)). Please update the table so the documented method names reflect the actual public API.
# Observability Core - Design Document

@fpfp100
Copy link
Copy Markdown

fpfp100 commented Mar 25, 2026

The Python PR #209 does not fully align with the nodejs implementation. The key gaps are below. Please take a look

TenantDetails still exists as a separate required parameter — Node.js absorbed it into AgentDetails.tenantId
Request is not unified — Python still has executionType (removed in Node.js) and lacks conversationId
InvokeAgentDetails not restructured — Should be renamed to InvokeAgentScopeDetails with only endpoint, while AgentDetails becomes a separate parameter
CallerDetails / UserDetails not restructured — Python doesn't have the wrapper CallerDetails (containing userDetails + callerAgentDetails) pattern
SpanDetails grouping doesn't exist — Span options remain as flat parameters
recordCancellation() and ERROR_TYPE_CANCELLED are missing
All scope start() signatures don't match — request should be required and first, tenant_details should be removed

@nikhilNava nikhilNava closed this Mar 26, 2026
@nikhilNava nikhilNava reopened this Mar 26, 2026
@nikhilNava
Copy link
Copy Markdown
Contributor Author

nikhilNava commented Mar 26, 2026

The Python PR #209 does not fully align with the nodejs implementation. The key gaps are below. Please take a look

TenantDetails still exists as a separate required parameter — Node.js absorbed it into AgentDetails.tenantId Request is not unified — Python still has executionType (removed in Node.js) and lacks conversationId InvokeAgentDetails not restructured — Should be renamed to InvokeAgentScopeDetails with only endpoint, while AgentDetails becomes a separate parameter CallerDetails / UserDetails not restructured — Python doesn't have the wrapper CallerDetails (containing userDetails + callerAgentDetails) pattern SpanDetails grouping doesn't exist — Span options remain as flat parameters recordCancellation() and ERROR_TYPE_CANCELLED are missing All scope start() signatures don't match — request should be required and first, tenant_details should be removed

Can you please review the comments, I believe the diff was taken against the main branch and not the PR branch.
Let me know if you have any other comments

@nikhilNava nikhilNava enabled auto-merge (squash) March 26, 2026 19:04
juliomenendez
juliomenendez previously approved these changes Mar 26, 2026
View reviewed changes
@fpfp100
Copy link
Copy Markdown

fpfp100 commented Mar 26, 2026

Since this is breaking change, can you update changelog?

Copilot AI review requested due to automatic review settings March 26, 2026 20:03
@nikhilNava
Copy link
Copy Markdown
Contributor Author

nikhilNava commented Mar 26, 2026

Since this is breaking change, can you update changelog?

done

Copilot AI reviewed Mar 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/scope_helpers/utils.py:27

  • AGENT_ROLE and _is_agentic() appear to be unused after removing get_execution_type_pair(). Consider removing them to avoid dead code and reduce confusion.
AGENT_ROLE = "agenticUser"


def _is_agentic(entity: Any) -> bool:
    if not entity:

@nikhilNava nikhilNava merged commit ff3bc83 into main Mar 26, 2026
13 checks passed
@nikhilNava nikhilNava deleted the nikhilc/AlignPublicAPI branch March 26, 2026 21:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@juliomenendez juliomenendez juliomenendez approved these changes

@fpfp100 fpfp100 fpfp100 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@nikhilNava @fpfp100 @juliomenendez @nikhilc-microsoft